Developer Documentation

QuickTime 4 API Documentation

3D Graphics Programming with QuickDraw 3D 1.5.4

Previous | QD3D Book | Overview | Chapter Contents | Next |

Application-Defined Routines

This section describes the routines you might need to define when using the routines in the QuickDraw 3D Pointing Device Manager.

TQ3ChannelGetMethod

You can define a function that QuickDraw 3D calls to get a channel of a controller.

typedef TQ3Status (*TQ3ChannelGetMethod) (
                     TQ3ControllerRef controllerRef,
                     unsigned long channel,
                     void *data,
                     unsigned long *dataSize);
controllerRef
A reference to a controller.
channel
An index into the list of channels associated with the specified controller. This value is always greater than or equal to 0 and less than the channel count specified at the time Q3Controller_New was called.
data
On entry, a pointer to a buffer. You should put the current value of the specified controller channel into this buffer.
dataSize
On exit, the number of bytes of data written to the specified buffer.

DESCRIPTION

Your TQ3ChannelGetMethod function should return, in the buffer pointed to by the data parameter, the current value of the controller channel specified by the controllerRef and channel parameters. Your function should also return, in the dataSize parameter, the size of that data. QuickDraw 3D allocates memory for the data buffer before it calls your function and deallocates the memory after your function has returned. The maximum number of bytes that the data buffer can hold is defined by a constant:

#define kQ3ControllerSetChannelMaxDataSize      256

SPECIAL CONSIDERATIONS

You need to define a channel-getting method only if you are writing a device driver for a controller. You can, however, call Q3Controller_GetChannel at any time to invoke a controller's channel-getting method.

RESULT CODES

Your channel-getting method should return kQ3Success if it is able to return the requested information and kQ3Failure otherwise.

SEE ALSO

See the description of Q3Controller_GetChannel on [link] for information on getting a controller's channels.

TQ3ChannelSetMethod

You can define a function that QuickDraw 3D calls to set a channel of a controller.

typedef TQ3Status (*TQ3ChannelSetMethod) (
                     TQ3ControllerRef controllerRef,
                     unsigned long channel,
                     const void *data,
                     unsigned long dataSize);
controllerRef
A reference to a controller.
channel
An index into the list of channels associated with the specified controller. This value is always greater than or equal to 0 and less than the channel count specified at the time Q3Controller_New was called.
data
On entry, a pointer to a buffer that contains the desired value of the specified controller channel. If this field contains the value NULL , you should reset the specified channel to a default or inactive value.
dataSize
On entry, the number of bytes of data in the specified buffer.

DESCRIPTION

Your TQ3ChannelSetMethod function should set the controller channel specified by the controllerRef and channel parameters to the value specified by the data parameter. The dataSize parameter specifies the number of bytes in the data buffer. QuickDraw 3D allocates memory for the data buffer before it calls your function and deallocates the memory after your function has returned. The maximum number of bytes that the data buffer can hold is defined by a constant:

#define kQ3ControllerSetChannelMaxDataSize                          256

SPECIAL CONSIDERATIONS

You need to define a channel-setting method only if you are writing a device driver for a controller. You can, however, call Q3Controller_SetChannel at any time to invoke a controller's channel-setting method.

RESULT CODES

Your channel-setting method should return kQ3Success if it is able to set the specified channel to the specified value and kQ3Failure otherwise.

SEE ALSO

See the description of Q3Controller_SetChannel on [link] for information on setting a controller's channels.

TQ3TrackerNotifyFunc

You can define a tracker notify function that QuickDraw 3D calls when a controller associated with a tracker has new data.

typedef TQ3Status (*TQ3TrackerNotifyFunc) (
                     TQ3TrackerObject trackerObject,
                     TQ3ControllerRef controllerRef);
trackerObject
A tracker object.
controllerRef
A reference to a controller.

DESCRIPTION

Your TQ3TrackerNotifyFunc function is called whenever any controller associated with a tracker has new data to be processed and the data meets or exceeds the current position and orientation thresholds for the tracker. The affected controller and tracker are passed in the controllerRef and trackerObject parameters. Your tracker notify function might, for example, schedule your application to awaken and redraw the scene.

SPECIAL CONSIDERATIONS

Your tracker notify function might be called at interrupt time, but it is never called reentrantly.

RESULT CODES

Your tracker notify function should return kQ3Success if it is successful and kQ3Failure otherwise.

SEE ALSO

See the description of Q3Tracker_New [link] for information on setting the notify function of a tracker.

Cursor Tracker Routines

© 1997 Apple Computer, Inc.

Previous | QD3D Book | Overview | Chapter Contents | Next |